JCSM Shareware Collection 1993 November

home *** CD-ROM | disk | FTP | other *** search

/ JCSM Shareware Collection 1993 November / JCSM Shareware Collection - 1993-11.iso / cl720 / bxprntjj.lzh / BOXPRINT.DOC < prev next >

Wrap

Text File | 1991-08-18 | 29KB | 564 lines

B O X P R I N T Welcome to BoxPrint. This product incorporates 5 main features: * A source-code reformattor * A single or cross-module tree diagrammer * A single or multi-module cross-referencer * The trade-mark 'BoxPrint' source-code enhancer * A more conservative 'Side-bar' source-code enhancer. In addition, it has a menu-driven interface for all these functions, including a dialog-box interface to allow you to define your source layout preferences for the reformatting feature. The product can be used from the command line, however if no options are specified, you will go into the menu interface. To install the program, simply copy the file 'BOXPRINT.EXE' and 'BOXPRINT.SYS' into your compiler directory. The disk contains other files, but these are for handling certain types of printers and includes a couple of test files, and you may or may not want any of them. You should be able to use all the features quite easily without any further reading, and there is even an on-line help page to help you with any difficulties. The rest of this manual is devoted to (a) explaining the functions in more detail, (b) describing how to get TAB characters handled correctly, (c) how C++ programs are handled and (d) printer configuration. REGISTERING BoxPrint is a Shareware program. The idea is that you are free to try it out, see how useful it is, and if you like it, you register your copy. There are several motivations for this: (a) This is how the ShareWare method works, (b) You will receive a malloc-debugging tool which allows you to easily debug your memory-allocation errors. It detects almost all abuses of the 'malloc' family of functions. You merely #include "dalloc.h" in your program and link with the "dalloc.c" module. It also allows you to explore your pointers & data structures. (c) An unregistered version of BoxPrint becomes slower each time you use it. This happens so gradually that I don't expect it to be much incentive, but it is there anyhow. In order to register, send $US25 or equivalent or $AUS25 to: Tim Cooper 31 Epping Ave EASTWOOD - 2122 AUSTRALIA 1 "BOX.BAT" "BOX.BAT" is a batch file BoxPrint's menu interface creates. It is both BoxPrint's configuration file and a valid batch file. If the list of files is blank in the menu, it will be created with "%1 %2 %3 etc" following the options, which DOS will replace with batch-file parameters (e.g. "BOX PROG1.C" will send the string "PROG1.C" to replace "%1".) The Print Spooler If you want the output to go to the print spooler, so that you can carry on with other tasks while the printer is going, you can select that option from the menu or command line. However, in order to work, a program called "PRINT.COM" or "PRINT.BAT" or "PRINT.EXE" must lie in the current path. This program, which normally comes included with your operating system, should lie in your "DOS" directory or system disk. TAB CHARACTERS BoxPrint assumes, by default, that the input text files contain TAB characters of width 8 characters. It also, by default, does not output any TABs (only spaces). If you have configured your editor to have TABs of a non-standard size, e.g. 4 characters, simply add the option /t4. (All options are case-insensitive). If you want TABs output, e.g. to reduce text file size, add to this option a comma and a digit representing the output TAB size, e.g. /t8,8 or /t4,8 etc. C++ CODE Since C++ is a superset of the C language, BoxPrint needs no special commands to select handling of C++ code. BoxPrint's reformatting feature will reformat C++ programs according to all but the most deviant layout styles. The BoxPrinting & Side-printing features will also work as expected in C++ programs. However, the Index and Tree functions are not guarunteed to be 100% valid. For efficiency and simplicity, BoxPrint uses a source analysis algorithm which does not open up header or include files, and so whether a token is interpreted as a type name, variable or function name depends on how it is used in the module given. This has the advantage in the case of C programs that macros are treated like the forms of code they represent, and so, for example, macros feature in the Tree diagrams and occur in the Indexes in the expected places (Indexes seperate functions from other identifiers). However, the system can be confused by situations such as variables being declared and initialised by a constructor in the 'type variable(params)' form, which looks like a function, which will lead to the Trees containing extraneous information and Indexes putting these variables in with the functions. However, this limitation does not lead to any more disastrous consequences, and apart from class definitions, even these features will work fairly normally. 2 Laser Printers Many laser-printers will work without any configuration options. However, the standard HP-laserjet compatible printer does not have an IBM-extended character set built in. This causes endless trouble. BoxPrint uses extended characters (those with values over 128) to draw boxes and trees, and often the programs contain them too. There are 4 solutions to this: 1 - If your laser printer does have the IBM extended character set built in, the problem is solved just by sending out the appropriate escape codes to select this character set. If you select the option /L1, you will probably get the print-out looking fine. This option automatically sends out, at the beginning, the sequence: 'ESC ( 0 E' to select the USASCII font. (And 'ESC ) 0 E' to deselect it). If this doesn't work, try the /L2 option to send the sequence 'ESC ( 10 U' and 'ESC ) 10 U' for the IBM-PC font. These options use the codes 'ESC (s1S' & 'ESC (s0S' to select & deselect italics. If this doesn't work, see the '/P' (printer escape code options) and look up your printer manual. 2 - If your laser printer doesn't have any such font built in or added on, BoxPrint provides a program 'HPFILTER.COM', a public domain program for printing box characters on laser printers. Simply call this program once, and it will take care of everything. IMPORTANT: If HPFILTER is installed already, another call will remove it. This is why you should either put it in your AUTOEXEC file or call it yourself at the beginning of each printing session. 3 - If you would like all the extended characters printed, you may consider buying a font cartridge or soft font from ShareWare or other software vendors. 4 - If for some reason this still doesn't work, you can always ______ get ASCII boxes using the '/a' option. You may like to contact Esprit de E (address at the end) with details of the problem. However, you will be able to solve most problems yourself by looking up your printer manual and using the /P.. options. 3 Dot Matrix Printers BoxPrint uses special box-printing characters to draw the boxes and tree diagrams. If you have a reasonably late-model dot matrix printer, BoxPrint will probably work without any configuration. Otherwise, you can try the following things: 1 - Most dot-matrix printers these days have the IBM extended character set built-in, although it may need an escape sequence to activate it. To send an escape sequence to select this character set, look up 'IBM (extended) character set' in your printer manual and set up that escape sequence with the '/Pi' command (see the appropriate section below). Some printers might even require you to set switches inside the printer, although this is rare. For example, NEC Pinwriters usually require the option: '/Pi28,73,1' to select this character set. 2 - Failing this, try the /E1 or /E2 or /E3 option. These make BoxPrint translate the box characters to corresponding characters in other older character sets. (They also set escape codes for italics and invoke the /X option, see below.) 3 - You can try to output a soft-font to your printer. On the distribution disk is a file 'DOTMAT.FNT' which should download the box characters as a soft-font to 8-pin printers which have redefinable characters and accept that format. To do this, put in your BOX.BAT file, before the call to BoxPrint: COPY/B DOTMAT.FNT PRN 4 - If the worst comes to the worst, you can always get ASCII ______ boxes by selecting the /A option. Otherwise you may like to contact Esprit de E with details of your printer, at the address at the back. However, most problems can be resolved by reading your printer manual and this manual first. 4 The Options Explained: BoxPrint options are not case sensitive. There are two kinds of options, commands and single-character options. /S means output to the standard output device (stdio) which is usually the screen. Use this if you just want to see what the program looks like without using a printer, or you can redirect it using the '>' character on the DOS command line into a file of your choice. /F means output to the file 'box.txt'. /{ means suppress the curly brackets. In other words, the boxes will no longer have the '{' and '}'. It's purely a matter of personal preference whether you want these left in or not. The boxes make them redundant, however experienced programmers might feel more comfortable with them still there. /Q means do a 'quick' printout. This is exactly the same except that vertical lines are omitted from the right side of the boxes. With dot matrix printers, it can reduce the time to print considerably because the print head does not need to travel so far. /L0 removes all escape sequences. /L1 will select an HP-compatible laser printer with the USASCII font. It assumes your printer has the IBM extended character set built into this font. See the section above. /L2 selects an HP-compatible laser printer with the IBM-PC font. It assumes you have the IBM extended character set built into this font. See the section above. /E0 removes all escape sequences. /E1 means select a different character set, common in pre-IBM printers. This option also invokes the /X option due to the fact that the older printers often print characters only 8 dots high. In this case, to make the boxes join up it is necessary to set line spacing to 8 dots and print spare lines (containing just the vertical-line characters) between every other line. To disable this option, type /X after the /E because /X is a toggle. /E2 and /E3 are similar to above, only they have different escape codes and character maps to the above. Between these three character maps and the DOTMAT.FNT file, most older dot-matrix printers should be supported. /X is an option not mentioned in the online help. It means print eXtra lines between every line of text, as described above in option /E1. This option is actually a toggle, with a standard printer it toggles on and with a /E -type printer it turns the extra lines off. /A means use standard ASCII characters to print the boxes. You can use this if your printer doesn't support extended IBM characters and is not currently supported by this program, or you want to take BoxPrinted files to other computer systems. 5 /P allows you to enter the various escape/control codes to completely configure your printer. /Pi is the escape/control sequence output at the beginning of the printout (the Initialising sequence). The default is nothing. Use this to set line spacing, font, etc. /Pf is the final sequence, output at the end of the printout (after indexes and trees). Use this if you need to restore printer options to their default settings. /P/* and /P*/ select the print style for comments. The first is output at the beginning of each comment (before the slash) and the other at the end (after the slash). C++ comments beginning with a double slash // and ending with a newline character are also supported. The default values are ESC-4 and ESC-5, which are common codes for selecting the italic character set. If your printer does not have italics, it will probably ignore these codes--however if they cause problems you can reset them to null strings, e.g. ... /P/* /P*/ ... . /Pw allows you to enter a new value for the printer width. The default is 80, which is fairly standard for monitors and printers. The codes are specified by a series of numbers separated by commas, with no spaces. The numbers are either decimal or, if preceded by 'H', hexadecimal. For example, the default sequences are equivalent to: /P/*27,52/P*/27,53/PW80 /Tn,m If you don't use the standard tabs interval of 8 characters in your source, you need to tell BoxPrint this using the /T option. For example, if you have configured your source editor to put tab stops at every 4 characters, use /T4 . The output can also uses tabs to cut down on excessive spaces. If you want this and your system copes with the TABs correctly, use the option /Tn,m (e.g. /T4,8) where n is the input tab interval and m is the output interval (usually 8). The default setting is /T8,0 where the zero means don't use spaces. Using BoxPrint's flexible handling of tabs and the /NORMAL option (see below), you can actually use it for a quite different purpose--namely to fix up your source code to get rid of tabs or insert tabs (to save memory and time) or change the size of tabs. For example, suppose you have just reconfigured your editor to put tabs at every 4th place. Without having to fix up all your source code by hand, you can convert it simply by typing: C>boxprint/f/t8,4/normal myprog C>copy box.txt myprog.c 6 /TREE means print a tree diagram(s) of all function calls. The diagram begins with the function 'main' (if it exists) at the root. This may be the only tree, however more often extra trees are needed: if a function is called from several different places in different procedures, and it calls at least one function in turn, it is put into a separate diagram. In other words, its name appears in the trees above but it also becomes the root of a new tree. This is to avoid repetition. If you have recursion in your program, these recursive calls are marked in the tree diagram by surrounding the function name in the leaf of the tree with brackets. Note that indirect recursion is not detected in this way. If the file being printed is a module file, i.e. without the function 'main', the roots of the trees are determined by finding all functions which are not called from within that module and putting them at the root of their own trees. If you want a tree diagram of your entire program, spread across many files, you can do this by naming the files one by one on the command line. BoxPrint will then examine all the files and link together all the functions and produce a correct tree diagram for the entire program. /TREEM is useful for multi-module programs. It prints the tree diagrams as above but with the appopriate module names written in italics next to each function. Example of use: C>boxprint/only tree file1 file2 file3 /INDEX means index all identifiers. At the end of the program will come a list of all identifiers in that file, including functions, variables, type identifiers, constants, macros and lables, excluding keywords (of course) and identifiers contained in the ANSI standard library. If you want more identifiers suppressed, e.g. commonly-used macros and library routines, you can set the "EXCLIST" environment variable to contain a list of words seperated by commas, e.g. "SET EXCLIST = or,and,not", or type the same string into the appropriate part on the menu. The Index comes in two parts, first come the functions and macros which act like functions, then everything else. The linenumbers where function bodies begin are marked by being surrounded in, naturally enough, curly braces { }. If you need to look up a function, just look for these. If you specify both /INDEX and /TREE, the order in which they come depends on the order you select the options. /NORMAL means print the file in its natural format, without boxes (but with comments in italics, unless you redefine them). /NUMBER means number the lines. This of course is also set by default if you select /INDEX. 7 /PAUSE means wait for a keypress between pages. This means that it prints one page (24 lines on the screen or 60 on the printer) and waits for a keypress before continuing. The page length can be redefined simply by following the option with the new page length e.g. /PAUSE66 if your printer prints this many lines per page. If you type /PAUSE9999, it will pause only before the Tree and Indexes and between different files. /PAGE means print form feeds (alias page ejects) which eject the current page from the printer. Again, this can be followed by the number of lines per page. If you direct the output to the screen, you will see little greek 'female' symbols marking where the page breaks would come. /PAGE9999 will print form feeds only between files and before Trees & Indexes. /PRINT means do the BoxPrint format printing of the file. This will put boxes around bodies of code and struct/union declarations and array initialisations, i.e. wherever a '{'/'}' pair occurs, with the exception of enum declarations and single-line array declarations. /FORMAT is the command to reformat source-code files according to one consistent style. The best way to define your own personal layout preferences is to use the menu interface, by moving the cursor onto the 'Change Format Options [ENTER]" button, and hitting <ENTER>. This will take you into a dialog box where you can simply define your own style by selecting appropriate options (usually by looking at examples and selecting the one you want) & setting the 'Indent Size' field which is by default 4 characters. The options there are fairly self-explanatory. However, a few notes can be made: The "func () / func()" selection specifies whether or not you want spaces between function names & the round brackets. (Although they always occur between "while/for/if/ switch" commands & their brackets.) The bottom right-hand box selects whether or not you want if { } else { } & while/for/do/switch commands & case statements seperated by blank lines. The advantage of this is that it sets your code out more, but the disadvantage is that less code then fits into your screen. The "Copy Blank Lines from Input File" option selects whether or not you want blank lines in the input file copied through to the output file. Programmers often use blank lines to seperate logically distinct sections of code, and BoxPrint of course cannot know itself what are logically distinct. So your file may be a little clearer if you set this option on, to effectively leave these blanks in the code. The "Remove leading blanks from Comments" refers to whether or not you want comments to always line up with the indentation, or if the spacing at the beginning of remark lines are to be retained. If there are diagrams in the code as remarks, they could be distorted if this option is selected, but normal text will probably look better with this option. 8 How to find bugs quicker with BoxPrint Used properly, BoxPrint can cut down on your bugs and debugging time and generally make life easier for you. There is a tendency among programmers to over-use their debuggers. Debuggers are so powerful these days that programmers are tempted to rely totally on these to find the bugs, rather than analysing the logic of the algorithm or the correctness of the code. Debuggers are good at finding out where a bug occurs, but not why. A general rule about using debuggers or analysing code is: As far as you know exactly what to expect in output, what values in the variables and where program control should be, you can use a debugger. If you are unsure about these things, you should no longer try to use the debugger to trace backwards to the source of the problem. In these cases, you should get your favourite source- code printer and take a hard-copy of the problem file, with an index of identifiers and a diagram of calls. The index will help you find typing mistakes, the tree diagram will help you understand the structure of the program, and if the program is well laid out, it will be easy to analyse the code and the logic. If you have curly brackets lacking or misplaced, this will become obvious with BoxPrint. If your indentation is out of sync with your brackets, this also becomes clear. The index can also be a powerful tool. It can be used to find errors due to reading uninitialised variables, or misspellings in variable names, etc. Every variable should have at least 3 or 4 references in the index. It needs to be declared initialised, assigned and read. These sometimes occur together, but in general every useful variable requires these 4 things and if it doesn't, you should have a good reason why not. Even a brief glance at the index can be useful in finding typing errors. The index is sorted alphabetically, ignoring leading underscores, and if there are two identifiers identical apart from case differences, they are put in the same place in the index but as separate entries. If you have made a typing error, the two spellings of the identifier will occur usually next to each other. If you have suggestions of improvements or new features, (I trust the program is not bugged) you can contact Tim Cooper of Esprit de E. Also, if you have a non-standard printer we don't support yet and would like to run BoxPrint on it with proper boxes (not the /A option) you could contact us with a few details. Tim Cooper Esprit de E software design 31 Epping Ave. EASTWOOD - 2122 ph. (02) 804 7473 9